> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jaypopat/cf_ai_duet/llms.txt
> Use this file to discover all available pages before exploring further.

# Pairing sessions

> Create and join collaborative programming sessions over SSH

## Overview

Duet enables instant pair programming through SSH. Connect to the server, create or join a room, and start collaborating with your team in seconds—no additional setup required.

## Creating a session

When you connect to Duet via SSH, you'll see the launch screen with two options:

<Steps>
  <Step title="Connect to the Duet server">
    ```bash theme={null}
    ssh your-username@duet.example.com -p 2222
    ```

    Your SSH username becomes your display name in the session.
  </Step>

  <Step title="Select 'Create room'">
    Navigate using arrow keys or press `c` to create a new room.
  </Step>

  <Step title="Add an optional description">
    Enter a description like "Backend refactoring" or "Bug fix session". This generates a readable workspace name (e.g., `backend-refactoring`).

    <Info>If you skip the description, Duet generates a random name like `cosmic-phoenix`</Info>
  </Step>

  <Step title="Share the room ID">
    After creation, you'll see a screen with your unique room ID (UUID format). Share this with your pair programming partner.

    ```
    Room created: a3f8e9d2-4c1b-4f3a-9e2b-8d7c6b5a4e3f
    ```
  </Step>

  <Step title="Press Enter to start">
    You'll be taken to the collaborative terminal where you can start working.
  </Step>
</Steps>

## Joining a session

To join an existing session:

<Steps>
  <Step title="Connect via SSH">
    ```bash theme={null}
    ssh alice@duet.example.com -p 2222
    ```
  </Step>

  <Step title="Select 'Join room'">
    Press `j` or navigate to "Join room" and press Enter.
  </Step>

  <Step title="Enter the room ID">
    Paste the UUID you received from the session host:

    ```
    Room ID: a3f8e9d2-4c1b-4f3a-9e2b-8d7c6b5a4e3f
    ```
  </Step>

  <Step title="Start collaborating">
    You'll immediately see the shared terminal and any existing chat history.
  </Step>
</Steps>

## Session architecture

Under the hood, Duet rooms are managed by the `room.Manager` which coordinates:

* **Client registration**: Each connection creates a `Client` with a unique ID and username
* **Event broadcasting**: All participants receive real-time events (joins, leaves, typing indicators)
* **Workspace isolation**: Each room gets its own directory at `/app/workspaces/{workspace-name}`
* **Resource cleanup**: When the last participant leaves, the workspace and all resources are destroyed

```go theme={null}
type Room struct {
    ID           string
    Description  string
    Host         string
    Connections  []*Client
    Terminal     *terminal.Terminal
    AIMessages   []AIMessage
    WorkspaceDir string
}
```

## Real-time presence

Duet keeps everyone informed about session activity:

<CardGroup cols={2}>
  <Card title="Join notifications" icon="user-plus">
    When someone joins, all participants see:

    ```
    alice joined
    ```
  </Card>

  <Card title="Leave notifications" icon="user-minus">
    When someone disconnects:

    ```
    bob left
    ```
  </Card>

  <Card title="Typing indicators" icon="keyboard">
    See who's actively typing in the terminal (debounced to 500ms)
  </Card>

  <Card title="User list" icon="users">
    The sidebar shows all connected users with their roles:

    * `alice (host) (you)`
    * `bob`
  </Card>
</CardGroup>

## Keyboard shortcuts

<Tabs>
  <Tab title="Launch screen">
    | Key            | Action                |
    | -------------- | --------------------- |
    | `c`            | Create a new room     |
    | `j`            | Join an existing room |
    | `↑/↓` or `k/j` | Navigate menu         |
    | `Enter`        | Select option         |
    | `q` or `Esc`   | Quit                  |
  </Tab>

  <Tab title="Room screen">
    | Key        | Action                          |
    | ---------- | ------------------------------- |
    | `Ctrl+L`   | Leave room and return to launch |
    | `Ctrl+G`   | Open AI assistant input         |
    | `Ctrl+R`   | Run command in sandbox          |
    | `Ctrl+A`   | Toggle AI sidebar visibility    |
    | `Ctrl+J/K` | Scroll AI chat up/down          |
  </Tab>
</Tabs>

## Session lifecycle

```mermaid theme={null}
sequenceDiagram
    participant Host
    participant Server
    participant Guest
    
    Host->>Server: SSH connection (create room)
    Server->>Server: Generate UUID & workspace
    Server-->>Host: Room ID displayed
    Host->>Guest: Share room ID
    Guest->>Server: SSH connection (join room)
    Server->>Server: Add client to room
    Server-->>Guest: Sync terminal & AI history
    Server-->>Host: "guest joined" notification
    Note over Host,Guest: Collaborative session active
    Guest->>Server: Disconnect
    Server-->>Host: "guest left" notification
    Host->>Server: Disconnect (last client)
    Server->>Server: Destroy room & cleanup workspace
```

## Error handling

<Warning>
  If you try to join a non-existent room ID, you'll see:

  ```
  Error: room not found
  ```

  Verify the room ID with the host and try again.
</Warning>

<Note>
  Rooms are ephemeral—they only exist while at least one participant is connected. If everyone leaves, the room and its workspace are permanently deleted.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Shared terminal" icon="terminal" href="/features/shared-terminal">
    Learn how the real-time terminal synchronization works
  </Card>

  <Card title="AI assistant" icon="sparkles" href="/features/ai-assistant">
    Use AI to help with your pair programming session
  </Card>
</CardGroup>